Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite and refactor all documentation #5534

Merged
merged 39 commits into from
Mar 6, 2023
Merged

Rewrite and refactor all documentation #5534

merged 39 commits into from
Mar 6, 2023

Conversation

David-Else
Copy link
Contributor

@David-Else David-Else commented Jan 14, 2023

Here is the (current state of the) rewrite of the Helix documentation following the discussion at
#5428

  • Improved readability, consistency, spelling, grammar, and best practices
    for software documentation
  • Added missing information and expanded / rewrote sections
  • Used triple tick sh for code blocks for text to be entered in the
    terminal
  • Formatted Markdown to 80 chars using Prettier.
  • Added some Table of Contents where I thought they were needed

This has been a huge undertaking, it is possible that I have made errors in the
parts I have re-written due to gaps in my knowledge, so I hope as many people as
possible can read it and confirm it is correct.

Please note, you can view Markdown diffs properly by clicking a button:
https://docs.github.com/en/repositories/working-with-files/using-files/working-with-non-code-files#rendering-differences-in-prose-documents

rendered_prose_diff
rendered_prose_changes

Another way to easily read it is to go to the Files Changed section with the diffs and click View File for each section:

Screenshot from 2023-01-14 15-52-29

TODO:

  • Refine parts of this draft pull request, I am not 100% happy with all of it
  • Fix the Windows section of Installing from source (waiting for feedback from @CptPotato)

NOTE: Part 2 to follow, splitting up and reorganizing the files into a better chapter structure.

@David-Else David-Else marked this pull request as draft January 14, 2023 15:58
@ayoub-benali
Copy link
Contributor

Thanks for taking care of this @David-Else 🎉 I was about to add a section about the supported LSP features but since you reworking the doc I will wait until is merged.

I had in mind something similar to this page: https://github.com/sublimelsp/LSP/wiki/LSP-specification-implementation-status
Should I added to this PR ?

@David-Else
Copy link
Contributor Author

@ayoub-benali That page sounds great, but I am not sure what to recommend at this stage. It could fit well in an appendices for reference. I need to get more feedback before I can think about adding more sections.

@CptPotato
Copy link
Contributor

@David-Else I created a PR over at https://github.com/David-Else/helix/pull/1 adding the windows specific install section as we discussed.

Update runtime directory instructions for windows
@bindsdev
Copy link

I have a suggestion for the section on themes. The available themes for Helix are not very well documented. A start would be to document a list of all the available themes. In addition, a preview for each theme should be provided. This would make picking a theme much easier since the user would just have to go to the documentation, look for the theme they like, and set it in their configuration. This would prevent the potentially tedious work of cycling through every available theme with the :theme command, trying to find the one you like the best.

@archseer
Copy link
Member

Themes: It's going to be a pain to maintain the list and the previews. You can already just tab through the list of themes and see the theme previewed live and with your preferred programming language snippet (surely pressing tab is no more tedious than loading a separate doc page and using the scroll wheel). I think this doesn't need to be a part of the docs.

book/src/guides/indent.md Outdated Show resolved Hide resolved
@bindsdev
Copy link

Themes: It's going to be a pain to maintain the list and the previews. You can already just tab through the list of themes and see the theme previewed live and with your preferred programming language snippet (surely pressing tab is no more tedious than loading a separate doc page and using the scroll wheel). I think this doesn't need to be a part of the docs.

That seems fair. I understand and can agree that it could be a pain to maintain that as part of the docs. 👍

@cd-a
Copy link
Contributor

cd-a commented Jan 16, 2023

Thanks for taking this on, @David-Else

@the-mikedavis
Copy link
Member

I force-pushed a version without the formatting changes (no hard-wrapping at 80 and no changes to table layout) following up on #5545 (comment). You can compare the changes here. I also saved a version of the branch before pushing here. This is based on the latest master now as well.

I wrote down a few notes, I'll post those as review comments now.

book/src/configuration.md Outdated Show resolved Hide resolved
book/src/guides/adding_languages.md Show resolved Hide resolved
book/src/keymap.md Outdated Show resolved Hide resolved
book/src/keymap.md Outdated Show resolved Hide resolved
book/src/remapping.md Outdated Show resolved Hide resolved
book/src/themes.md Outdated Show resolved Hide resolved
book/src/usage.md Outdated Show resolved Hide resolved
book/src/usage.md Outdated Show resolved Hide resolved
book/src/usage.md Outdated Show resolved Hide resolved
book/src/usage.md Outdated Show resolved Hide resolved
David-Else and others added 2 commits January 29, 2023 14:57
Apply the suggestions that can be committed from the GitHub web interface.

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
…avid-Else/helix into rewrite-and-refactor-all-documentation
book/src/themes.md Outdated Show resolved Hide resolved
David-Else and others added 4 commits February 1, 2023 15:23
Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>
…avid-Else/helix into rewrite-and-refactor-all-documentation
@David-Else
Copy link
Contributor Author

@archseer This has been my first time responding to a GitHub code review, should I always reply to suggestions or just hit resolved when I have completed them? I have been pressing the resolved button in cases where no comment was needed.

There is still the matter of title case in headings, you have corrected many of them to be lower case, shall I grep all the documentation and make sure all titles are lower-case (keeping things like proper nouns upper-case)?

There are still a few questions I left in the review comments to be answered, but other than that I think I have made all the corrections asked of me. The install page in particular looks really good now, so much better than it currently is on so many levels :)

book/src/install.md Outdated Show resolved Hide resolved
@David-Else
Copy link
Contributor Author

I have now done everything in the code reviews, anything more I need to do?

@pascalkuthe pascalkuthe added A-documentation Area: Documentation improvements E-medium Call for participation: Experience needed to fix: Medium / intermediate S-waiting-on-review Status: Awaiting review from a maintainer. labels Feb 18, 2023
Copy link
Member

@the-mikedavis the-mikedavis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just some minor comments/typos. Otherwise this looks good IMO

(I also merged in master since I've been merging docs changes that added conflicts. Hope it's not a bother!)

book/src/guides/adding_languages.md Outdated Show resolved Hide resolved
book/src/install.md Show resolved Hide resolved
book/src/install.md Outdated Show resolved Hide resolved
David-Else and others added 3 commits March 1, 2023 13:48
Fix grammar typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
Fix tree sitter typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
@the-mikedavis the-mikedavis requested a review from archseer March 3, 2023 16:11
Copy link
Member

@archseer archseer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this! Documentation really needed some maintenance and I think this will improve the initial experience for any new user 🎉

@archseer archseer merged commit 707457c into helix-editor:master Mar 6, 2023
@cd-a
Copy link
Contributor

cd-a commented Mar 6, 2023

Agree, this is great work. Thank you!

@archseer archseer mentioned this pull request Mar 8, 2023
sagnibak pushed a commit to sagnibak/helix that referenced this pull request Mar 21, 2023
* Rewrite and refactor all documentation

* Rewrite and refactor the guides

* update runtime directory instructions for windows

* Update the Ubuntu 3rd party repo section with 22.10

* Merge from upstream

* Rewrite and refactor all documentation

* Apply suggestions from code review

Apply the suggestions that can be committed from the GitHub web interface.

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Add Windows themes folder

Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>

* Apply the rest of the suggestions from the code review

* Revert "Apply the rest of the suggestions from the code review"

This reverts commit 498be1b.

* Revert "Merge branch 'rewrite-and-refactor-all-documentation' of github.com:David-Else/helix into rewrite-and-refactor-all-documentation"

This reverts commit 7c84042, reversing
changes made to d932969.

* Apply code review suggestions

* Changes after re-reading all documents

* Missed a full stop

* Code review suggestions and remove macOS and Windows specific sections

* Add OpenBSD to heading

* Add back macOS and Windows sections and further simplify and improve

* Change wording to nightly

* Remove README installation section and turn into a link

* Simplify building from source and follow code review suggestions

* Code review revisions

* Fix copy paste mistake

* Apply the latest code review suggestions

* More small code review items

* Change minor modes for code review

* Fix link and typos

* Add note that you need a c++ compiler to install the tree-sitter grammars

* Add pacman example

* Make sure all headings are lower case

* Revert to the original passage adding a reference to Windows that was missing

* Update book/src/guides/adding_languages.md

Fix grammar typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Update book/src/install.md

Fix tree sitter typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Remove TOC links to main heading

---------

Co-authored-by: CptPotato <3957610+CptPotato@users.noreply.github.com>
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>
@David-Else David-Else deleted the rewrite-and-refactor-all-documentation branch April 18, 2023 12:59
wes-adams pushed a commit to wes-adams/helix that referenced this pull request Jul 4, 2023
* Rewrite and refactor all documentation

* Rewrite and refactor the guides

* update runtime directory instructions for windows

* Update the Ubuntu 3rd party repo section with 22.10

* Merge from upstream

* Rewrite and refactor all documentation

* Apply suggestions from code review

Apply the suggestions that can be committed from the GitHub web interface.

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Add Windows themes folder

Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>

* Apply the rest of the suggestions from the code review

* Revert "Apply the rest of the suggestions from the code review"

This reverts commit 498be1b.

* Revert "Merge branch 'rewrite-and-refactor-all-documentation' of github.com:David-Else/helix into rewrite-and-refactor-all-documentation"

This reverts commit 7c84042, reversing
changes made to d932969.

* Apply code review suggestions

* Changes after re-reading all documents

* Missed a full stop

* Code review suggestions and remove macOS and Windows specific sections

* Add OpenBSD to heading

* Add back macOS and Windows sections and further simplify and improve

* Change wording to nightly

* Remove README installation section and turn into a link

* Simplify building from source and follow code review suggestions

* Code review revisions

* Fix copy paste mistake

* Apply the latest code review suggestions

* More small code review items

* Change minor modes for code review

* Fix link and typos

* Add note that you need a c++ compiler to install the tree-sitter grammars

* Add pacman example

* Make sure all headings are lower case

* Revert to the original passage adding a reference to Windows that was missing

* Update book/src/guides/adding_languages.md

Fix grammar typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Update book/src/install.md

Fix tree sitter typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Remove TOC links to main heading

---------

Co-authored-by: CptPotato <3957610+CptPotato@users.noreply.github.com>
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-documentation Area: Documentation improvements E-medium Call for participation: Experience needed to fix: Medium / intermediate S-waiting-on-review Status: Awaiting review from a maintainer.
Projects
None yet
Development

Successfully merging this pull request may close these issues.